home *** CD-ROM | disk | FTP | other *** search
/ The Atari Compendium / The Atari Compendium (Toad Computers) (1994).iso / files / prgtools / programm.ing / ams__l~1.zoo / man / screen.man < prev    next >
Encoding:
Text File  |  1993-09-05  |  6.3 KB  |  190 lines
  1.                         ATARI MACHINE SPECIFIC LIBRARY
  2.  
  3.  
  4.  
  5. NAME
  6.      Screen - support for Atari standard resolution screens
  7.  
  8. SYNOPSIS
  9.      #include <Screen.h>
  10.  
  11.      class Screen
  12.  
  13. DESCRIPTION
  14.      When writing machine specific programs, the Atari programmer will
  15.      often work directly with screen images.  Many drawing programs
  16.      exist for creating screen images, so these are a logical base for
  17.      developing graphical applications.
  18.  
  19.      Regardless of screens displayed during a program, the original
  20.      display and colour palette are restored upon termination.
  21.  
  22. CLASSES
  23.      The class Screen encapsulates the concept of a screen image.
  24.      A Screen's image can be transfered to and from disk, displayed,
  25.      and modified.  All Screen-modifying routines are in other modules.
  26.  
  27.      Screens are memory areas (possibly extending above and below the
  28.      visible area) with palettes.  Palettes are fairly independent, but
  29.      are included here, because most picture file formats include the
  30.      palette in the file.
  31.  
  32. CLASS MEMBERS
  33.   Screen::
  34.  
  35.      Screen()
  36.          A screen for the current resolution
  37.  
  38.      Screen(const Screen&)
  39.          A screen with a duplicate image and palette of another screen
  40.  
  41.      Screen(Resolution)
  42.          A screen for a specific resolution
  43.  
  44.      Screen(Resolution, short LinesAbove, short LinesBelow)
  45.          A screen for a specific resolution, with extra memory allocated
  46.          above and below the normal bounds of the screen.
  47.  
  48.      Screen(short LinesAbove, short LinesBelow)
  49.          A screen for the current resolution, with extra memory allocated
  50.          above and below the normal bounds of the screen.
  51.  
  52.      Screen(long *At)
  53.          A screen using the memory at a specific location.
  54.          If the constant DESKSCREEN is used, the location of the current
  55.          screen is used.
  56.  
  57.      Screen(const char *filename)
  58.          A screen as specified in the given picture file.
  59.          May cause !() to be true (ie. it may fail - if the file is bad).
  60.  
  61.      int operator !()
  62.          'does-not-exist' operator (eg. init file not found)
  63.  
  64.      void Clear()
  65.          Clear the screen.
  66.  
  67.      void ShowPalette()
  68.          Change the current palette to that of the screen.
  69.  
  70.      void Show();    // Physically show
  71.          Change the current physically displayed screen to this one.
  72.          (Note:  refer to DoubleBuffer for more useful interface)
  73.  
  74.      void Use()
  75.          Change the current logically active screen to this one.
  76.          (Note:  refer to DoubleBuffer for more useful interface)
  77.  
  78.      short* Color()
  79.      short* Colour()
  80.          Returns array of RGB.  eg:  scr.Colour()[4]=0x123
  81.  
  82.      char *Location()
  83.          Returns the displayable area of the screen (ie. does not
  84.          include "lines above" or "line below" that are specified
  85.          in some constructors).
  86.  
  87.      Resolution Rez()
  88.          Returns the resolution associated with a given screen.
  89.  
  90.      int Load(const char*);
  91.      int LoadPalette(const char *);
  92.          Load in format appropriate to filename extension, or if no
  93.          extension, then whichever file can be found by adding a supported
  94.          file format extension.
  95.      
  96.      int Save(const char*);
  97.          Save in format appropriate to filename extension.
  98.  
  99.      These routines access the file formats explicitly:
  100.      int LoadDegas(const char *);
  101.      int SaveDegas(const char *);
  102.      int LoadDegasPalette(const char *);
  103.      int LoadCrackArtPalette(const char *);
  104.      int LoadCrackArt(const char *);
  105.      int SaveCrackArt(const char *, int Compression=3);
  106.           Compression 0 = minimal compression attempt
  107.           Compression 8 = maximal compression attempt
  108.  
  109. USAGE
  110.      Newly created Screens are NOT cleared.  The programmer will usually
  111.      clear them, or load images into them.
  112.  
  113. FILES
  114.      The LoadDegas and SaveDegas routines support TT resolutions as
  115.      logical extensions (all still have 16 colours, except TTLow which
  116.      has 256 colours).  LoadCrackArt and SaveCrackArt routines also
  117.      support TT resolutions logically.
  118.      
  119.      Note that CrackArt is a compressed format.
  120.      
  121.      Load(filename) and Save(filename) methods use these extensions:
  122.      
  123.       CrackArt  Degas  Resolution  Getrez()
  124.        CA1       PI1    STLow       0
  125.        CA2       PI2    STMedium    1
  126.        CA3       PI3    STHigh      2
  127.        CA8       PI8    TTLow       7
  128.        CA5       PI5    TTMedium    4
  129.        CA6       PI6    TTHigh      5
  130.      
  131.       ie.
  132.         "CA"+('1'+Resolution)
  133.         "PI"+('1'+Resolution)
  134.  
  135.      For further details of these formats, the best source is
  136.      Dave Baggett's "ST Picture Formats" document (picfmts.doc),
  137.      and the AMS library sources.
  138.  
  139.      Note that at time of writing, the CrackArt CA3 format as
  140.      specified by the CrackArt authors had a slight bug in that
  141.      it does not save the palette.  This probably arose because
  142.      the CrackArt drawing program is a low-resolution only program,
  143.      and so the format was never really used.  The problem is not
  144.      very relevant on the ST since STHigh is monochrome anyway, but
  145.      on the TT, STHigh can have any two arbitrary colours.
  146.  
  147. SEE ALSO
  148.      Resolution, DoubleBuffer, EasySprite
  149.  
  150. DIAGNOSTICS
  151.      When Screen objects are created with the Screen(char *) method
  152.      (ie. load from file), the programmer should chech the success
  153.      by using operator!(), for example:
  154.  
  155.           Screen foo("foo.pi1");
  156.           if (!foo) {
  157.               printf("failed!\n");
  158.               exit(1);
  159.           }
  160.  
  161.      Also, Load*() and Save*() methods return a success value.  0 for
  162.      failure, non-0 for success.  For example:
  163.  
  164.           Screen foo;
  165.  
  166.           if (foo.Load("foo.pi1")) {
  167.               printf("failed!\n");
  168.               exit(1);
  169.           }
  170.  
  171. BUGS
  172.      Screen::Show() does not change the resolution.  This is because
  173.      the standard TOS routine to do this also clears the screen, which
  174.      is not the usual requirement.
  175.  
  176. AUTHOR
  177.      Warwick Allison, 1992.
  178.      warwick@cs.uq.oz.au
  179.  
  180. COPYING
  181.      This functionality is part of the Atari Machine Specific Library,
  182.      and is Copyright 1992 by Warwick W. Allison.
  183.  
  184.      The Atari Machine Specific Library is free and protected under the
  185.      GNU Library General Public License.
  186.  
  187.      You are free to copy and modify these sources, provided you acknowledge
  188.      the origin by retaining this notice, and adhere to the conditions
  189.      described in the GNU LGPL.
  190.